"""
辅助函数模块

提供程序中常用的工具函数，包括：
1. 物理量单位转换
2. 数值计算辅助函数
3. 数据处理和验证函数
"""

import numpy as np
from typing import Union, List, Dict, Any, Tuple

def celsius_to_kelvin(celsius: float) -> float:
    """
    将摄氏度转换为开尔文
    
    参数:
        celsius (float): 摄氏度温度
        
    返回:
        float: 开尔文温度
    """
    return celsius + 273.15

def kelvin_to_celsius(kelvin: float) -> float:
    """
    将开尔文转换为摄氏度
    
    参数:
        kelvin (float): 开尔文温度
        
    返回:
        float: 摄氏度温度
    """
    return kelvin - 273.15

def pa_to_mpa(pa: float) -> float:
    """
    将帕斯卡转换为兆帕
    
    参数:
        pa (float): 帕斯卡压力
        
    返回:
        float: 兆帕压力
    """
    return pa / 1e6

def mpa_to_pa(mpa: float) -> float:
    """
    将兆帕转换为帕斯卡
    
    参数:
        mpa (float): 兆帕压力
        
    返回:
        float: 帕斯卡压力
    """
    return mpa * 1e6

def calculate_hydraulic_diameter(
    flow_area: float,
    wetted_perimeter: float
) -> float:
    """
    计算水力直径
    
    参数:
        flow_area (float): 流通面积 (m²)
        wetted_perimeter (float): 湿周长 (m)
        
    返回:
        float: 水力直径 (m)
    """
    return 4.0 * flow_area / wetted_perimeter

def calculate_reynolds_number(
    velocity: float,
    hydraulic_diameter: float,
    density: float,
    viscosity: float
) -> float:
    """
    计算雷诺数
    
    参数:
        velocity (float): 流体速度 (m/s)
        hydraulic_diameter (float): 水力直径 (m)
        density (float): 流体密度 (kg/m³)
        viscosity (float): 动力粘度 (Pa·s)
        
    返回:
        float: 雷诺数
    """
    return density * velocity * hydraulic_diameter / viscosity

def calculate_mass_flux(
    velocity: float,
    density: float
) -> float:
    """
    计算质量流量
    
    参数:
        velocity (float): 流体速度 (m/s)
        density (float): 流体密度 (kg/m³)
        
    返回:
        float: 质量流量 (kg/m²·s)
    """
    return velocity * density

def validate_positive(
    value: float,
    name: str
) -> None:
    """
    验证数值是否为正数
    
    参数:
        value (float): 待验证的数值
        name (str): 数值的名称
        
    异常:
        ValueError: 当数值不为正数时抛出
    """
    if value <= 0:
        raise ValueError(f"{name}必须为正数，当前值为{value}")

def validate_range(
    value: float,
    name: str,
    min_value: float,
    max_value: float
) -> None:
    """
    验证数值是否在指定范围内
    
    参数:
        value (float): 待验证的数值
        name (str): 数值的名称
        min_value (float): 最小值
        max_value (float): 最大值
        
    异常:
        ValueError: 当数值不在范围内时抛出
    """
    if value < min_value or value > max_value:
        raise ValueError(
            f"{name}必须在[{min_value}, {max_value}]范围内，当前值为{value}"
        )

def calculate_average(values: np.ndarray) -> float:
    """
    计算数组平均值
    
    参数:
        values (np.ndarray): 数值数组
        
    返回:
        float: 平均值
    """
    return np.mean(values)

def calculate_relative_error(
    value: float,
    reference: float
) -> float:
    """
    计算相对误差
    
    参数:
        value (float): 当前值
        reference (float): 参考值
        
    返回:
        float: 相对误差
    """
    return abs(value - reference) / abs(reference)

def interpolate_linear(
    x: float,
    x1: float,
    x2: float,
    y1: float,
    y2: float
) -> float:
    """
    线性插值
    
    参数:
        x (float): 待插值点
        x1 (float): 已知点1的x坐标
        x2 (float): 已知点2的x坐标
        y1 (float): 已知点1的y值
        y2 (float): 已知点2的y值
        
    返回:
        float: 插值结果
    """
    return y1 + (y2 - y1) * (x - x1) / (x2 - x1) 